PtPassword()

Prompt for a password

Synopsis:

int PtPassword( PtWidget_t *parent,
                PhPoint_t const *location,
                char const *title,
                PhImage_t const *image,
                char const *message,
                char const *msg_font,
                char const **buttons,
                char const **btn_fonts,
                char const *text_font,
                int (*validate_f)(void *,char const *),
                void *validate_data,
                char const *echo,
                int flags );

Arguments:

parent

A pointer to the parent widget of the dialog (usually a window). By setting the flags, you can block the parent and/or position the dialog relative to it.

location

A pointer to a PhPoint_t structure that specifies the location of the dialog relative to the parent or console, depending on the flags. If location is NULL, the dialog is centered.

title

The title for the dialog. If you don't want a title bar, set this argument to NULL.

image

A pointer to a PhImage_t structure that specifies an icon to display beside the message. If you don't want an icon, set this argument to NULL.

message

The message to display.

msg_font

The font for the message text; the default is TextFont09. You should create the font name by calling PfGenerateFontName().

buttons

A pointer to an array of strings to be displayed in the buttons. If non-NULL, this array must contain exactly two strings. The first is for the cancel button, and the second is for the accept button.

All the button-text arguments let you define shortcut keys. Place an ampersand (&) in front of the character that you want to be the shortcut. For example, if you specify &Yes, the Y is underlined in the button, and you can press y or Y to select the button.

If buttons is NULL, the function uses &Cancel and &Ok for the buttons.

btn_fonts

A pointer to an array of strings naming the fonts to be used in the buttons. If this argument is NULL, TextFont09 is used for all the buttons. Otherwise, this array must contain at least btnCount font names. You should create the font names by calling PfGenerateFontName().

text_font

The name of the font to use for the text. You should create the font name by calling PfGenerateFontName().

validate_f

A pointer to a password-validation function, which is of the form:

int validate( void *data,
              char const *password_entered )
  

The arguments to the validation function are:

• data — arbitrary data you need in the function. It's the validate_data that you pass to PtPassword().
• password_entered — the password that the user typed.

The validation function must return one of:

• Pt_PWD_ACCEPT — the password is acceptable.
• Pt_PWD_RETRY — the password is unacceptable. Let the user try again.
• Pt_PWD_REJECT — the password is unacceptable, Don't let the user try again.

validate_data

User data that's passed to your validation function.

echo

A multibyte character to replace the characters that the user types. If NULL, * is used. Specify "" if you don't want any echoing to take place (i.e. the text field appears non-interactive but there's no indication of how many characters the user types, which might be appealing for higher security restrictions).

flags

Flags that define the behavior for the dialog. This can be up to one of the following:

• Pt_CENTER — center the dialog.
• Pt_LEFT — left-align the dialog (the default).
• Pt_RIGHT — right-align the dialog.

with any combination of the following:

• Pt_BLOCK_ALL — block all of the application's windows while the dialog is displayed.
• Pt_BLOCK_PARENT — block the widget specified by the parent argument (if non-NULL).
• Pt_ESC_DISABLE — disable the ESC key as a means of dismissing the dialog.
• Pt_MODAL — the same as Pt_BLOCK_ALL.
• Pt_RELATIVE — position the dialog relative to the given parent widget. If this bit isn't set or parent is NULL, the dialog is positioned relative to the current console.

Pt_BLOCK_ALL overrides Pt_BLOCK_PARENT.

Library:

ph

Description:

This function displays a dialog that prompts the user for a password.

Returns:

Pt_PWD_ACCEPT

The user typed an acceptable password.

Pt_PWD_REJECT

The password that the user typed was rejected.

Pt_PWD_CANCEL

The user aborted the operation.

Otherwise, the function returns -1 to indicate some lower-level error (e.g. the dialog couldn't be created).

Classification:

Photon

See also:

PfGenerateFontName(), PhImage_t, PhPoint_t, PtAlert(), PtNotice(), PtPrompt()

“Dialog modules” in the Working with Modules chapter of the Photon Programmer's Guide